<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
<HTML><HEAD>
<TITLE>IBM Visualization Data Explorer Programmer&#39;s Reference</TITLE>

<META HTTP-EQUIV="abstract" CONTENT="IBM Visualization Data Explorer
Programmer&#39;s Reference">
<META HTTP-EQUIV="contact" CONTENT="IBM Visualization Data Explorer
(ibmdx@watson.ibm.com)">
<META HTTP-EQUIV="owner" CONTENT="IBM Visualization Data Explorer
(ibmdx@watson.ibm.com)">
<META HTTP-EQUIV="updated" CONTENT="Tue, 16 Sep 1997 ">
<META HTTP-EQUIV="review" CONTENT="Fri, 14 Aug 1998 ">

<META HTTP-EQUIV="keywords" CONTENT="GRAPHICS VISUALIZATION VISUAL PROGRAM DATA
MINING">
<meta http-equiv="content-type" content="text/html;charset=ISO-8859-1">
</HEAD><BODY BGCOLOR="#FFFFFF">

<A NAME="Top_Of_Page"></A>
<H1>IBM Visualization Data Explorer Programmer&#39;s Reference</H1>
<B>&#91; <A HREF="#Bot_Of_Page">Bottom of Page</A> &#124; <A
HREF="progu021.htm">Previous Page</A> &#124; <A HREF="progu023.htm">Next
Page</A> &#124; <A HREF="../proguide.htm#ToC">Table of Contents</A> &#124; <A
HREF="progu015.htm#PToC5">Partial Table of Contents</A> &#124; <A
HREF="progu344.htm#HDRINDEX_START">Index</A> &#93;</B><HR><P>

<HR>
<H1><A NAME="HDRNEEDMOD" HREF="../proguide.htm#ToC_50">Chapter 4. What you need to
know about Data Explorer to write a Module</A></H1>
<P><A NAME="PToC6" HREF="../proguide.htm#ToC">Partial Table-of-Contents</A>
<MENU>
<LI><A NAME="PToC_51" HREF="#HDRDATAM">4.1 Data Explorer Data Model</A>
<LI><A NAME="PToC_52" HREF="progu023.htm#HDRMEMNG">4.2 Memory Management</A>
<MENU>
<LI><A NAME="PToC_53" HREF="progu023.htm#HDRMEMALC">Allocating and Freeing
Memory</A>
<LI><A NAME="PToC_54" HREF="progu023.htm#Header_54">Reference Counts</A>
</MENU>
<LI><A NAME="PToC_55" HREF="progu024.htm#HDREXECM">4.3 Data Explorer Execution
Model</A>
</MENU><HR><P>
This chapter contains the basic information about the underlying data
model, execution model and memory management model for Data Explorer. It is
strongly recommended that you read and understand this short chapter
before writing a module.

<HR>
<H2><A NAME="HDRDATAM" HREF="#PToC_51">4.1 Data Explorer Data Model</A></H2>
<P>
<A NAME="IDX208"></A>
<A NAME="IDX209"></A>
<I>Fields</I> are the fundamental informational entities in
Data Explorer.
A Field contains the components that carry the actual numbers.
<A NAME="IDX210"></A>
The "positions" component, for instance, contains the positions of
a data set, while the
<A NAME="IDX211"></A>
"data" component contains the data values (e.g., temperatures).
<A NAME="IDX212"></A>
Groups are higher-level structures and may consist of Fields or other
Groups (see <A HREF="progu044.htm#TBLCL">Table 1</A>).
<P>
Generally, a component consists of an Array of data, information
describing the data (i.e., its type, dimensionality, or both),
and a name associated with the component.
Standard components include "positions," "data," and
"colors."
The name of a component does not usually imply anything about its
characteristics (e.g., its data type or dimensionality).

In addition, components typically carry attributes which indicate other
characteristics of the component.
<P>
For example, a "data" component should always have a "dep"
attribute with a value of either "positions" or "connections".
This attribute tells modules operating on the field whether the data are
position-dependent or connection-dependent. Position-dependent data are
associated one-to-one with the "positions" of a field, and data
values can be interpolated at other positions in the field using the
"connections" component if present. Connection-dependent data are
associated one-to-one with the "connections" of a field, and data
values are assumed constant within each connection.
<P>
Another example of a required attribute is that the "connections"
component have a "ref" attribute of "positions". This
indicates to Data Explorer that the items in the connections component are to be
interpreted as indices into the "positions" component. In addition,
the "connections" component must have an "element type"
attribute indicated the type of the connection (e.g. "triangles",
"quads", etc.). For more information on component attributes, see
<A HREF="usrgu025.htm#TBLCOMPATT">Table 2</A> in <I>IBM Visualization Data
Explorer User&#39;s Guide</I>.

<P>
Module operations typically take place at the Field level and involve
changing or creating components.
For example:
<UL COMPACT>
<LI>The Compute module may create an output Field whose data component
is the sum of the "data" components of two input Fields.
<LI>The AutoColor module creates an output Object whose "colors"
component is based on the "data" component of the input
Field.
<LI>The Isosurface module creates an output Object whose "positions"
and "connections" components describe a surface of constant
value in the input Object&#39;s data Field.
</UL>
<P>
Modules in Data Explorer are generally required to be pure functions and
they must not modify their inputs.
Instead, to modify the "data" component of an input Object, a
module must first make a copy of the Object.
Note that the data model allows the module to copy the structure
without copying the data.
Some modules (e.g., Isosurface) create a completely new Object for
the output (as will be illustrated in later chapters).
<P>
Because a module typically works by manipulating the components of a
Field, and because its input may be a more complicated
Object consisting of Groups, it must often operate
recursively.
In particular, the efficient use of multiple processors requires that
a parallel module must be able to traverse Groups, since
partitioning creates a special type of Group called a
Composite Field.
<P>
For example, a module designed to add a number to every data value in
each data component of an input Object first makes a copy of
the input Object on which it is to operate.
This copy duplicates the structure of the input Object (the hierarchy
of Groups and Fields) but not the Arrays containing the values
in the components of the Fields.
In the worker part of the routine, a new "data" component is
created to hold the modified data values (the other components
can be shared with the input Object, since they will not
be modified).
<P>
The worker part of the routine first queries the Object to determine
whether it is a Field or a Group:
<UL COMPACT>
<LI>If it is a Field, the routine extracts the "data" component of
the input Object, creates a new "data" component, places it
in the output Object, computes the sum, puts the result
in the new component, and returns.
<LI>If it is a Group, the routine extracts each of the group&#39;s
children and recursively calls itself for each child to determine
whether that child is a Field or a Group, and so on.
(See <A HREF="progu025.htm#HDRMODEXSC">Chapter 5. "Working with Data"</A> for an
illustration of how a module
performs this procedure on an input Object.)
</UL>
<P><HR><B>&#91; <A HREF="#Top_Of_Page">Top of Page</A> &#124; <A
HREF="progu021.htm">Previous Page</A> &#124; <A HREF="progu023.htm">Next
Page</A> &#124; <A HREF="../proguide.htm#ToC">Table of Contents</A> &#124; <A
HREF="#PToC6">Partial Table of Contents</A> &#124; <A
HREF="progu344.htm#HDRINDEX_START">Index</A> &#93;</B> <br><b>&#91;<a
href="../allguide.htm">Data Explorer Documentation</a>&nbsp;&#124;&nbsp;<a
href="../qikguide.htm">QuickStart Guide</a>&nbsp;&#124;&nbsp;<a
href="../usrguide.htm">User&#39;s Guide</a>&nbsp;&#124;&nbsp;<a
href="../refguide.htm">User&#39;s Reference</a>&nbsp;&#124;&nbsp;<a
href="../proguide.htm">Programmer&#39;s Reference</a>&nbsp;&#124;&nbsp;<a
href="../insguide.htm">Installation and Configuration
Guide</a>&nbsp;&#93;</b><br><p><b>&#91;<a
href="http://www.research.ibm.com/dx">Data Explorer Home
Page</a>&#93;</b><p><HR ALIGN=LEFT WIDTH=600><b>&#91;<A
HREF="http://www.ibm.com/">IBM Home Page</A>&nbsp;&#124;&nbsp;<A
HREF="http://www.ibm.com/Orders/">Order</A>&nbsp;&#124;&nbsp;<A
HREF="http://www.ibm.com/Search/">Search</A>&nbsp;&#124;&nbsp;<A
HREF="http://www.ibm.com/Assist/">Contact IBM</A>&nbsp;&#124;&nbsp;<A
HREF="http://www.ibm.com/Legal/">Legal</A>&nbsp;&#93;</b><hr><p>
<A NAME="Bot_Of_Page"></A>
</BODY></HTML>
